home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / forth / pfe-0.000 / pfe-0 / pfe-0.9.13 / help / misc.hlp < prev    next >
Encoding:
Text File  |  1995-02-25  |  8.4 KB  |  279 lines
  1. #
  2. # misc.hlp ---        Online help strings for pfe,
  3. #            miscellaneous nice words
  4. # (duz 16Sep94)
  5. #
  6.  
  7. : COLD ( ... x --- ) [FIG]
  8. re-initializes the forth system. Closes all files, cleans the
  9. dictionary and all stacks.
  10.  
  11.  
  12. : .LINE ( line blk --- ) [FIG]
  13. displays the specified line of the specified block. No spaces before,
  14. one space after, no newlines are output.
  15.  
  16.  
  17. : CSP ( --- a-addr ) [FIG]
  18. variable used for error checking during compilation. See !CSP and
  19. ?CSP.
  20.  
  21.  
  22. : !CSP ( --- ) [FIG]
  23. stores the actual stack pointer into the variable CSP. The data stack
  24. is used as control flow stack during compilation. Use !CSP in words
  25. that switch to compiling state. See ?CSP.
  26.  
  27.  
  28. : ?CSP ( --- ) [FIG]
  29. compares the actual stack pointer with the contents of the variable
  30. CSP (compiler security pointer). An error is detected when both are
  31. not equal and -22 THROW (control structure mismatch) is executed.
  32. When the actual data stack pointer equals the value in CSP nothing
  33. happens. Use ?CSP in words that switch from compiling back to
  34. interpreting state to be sure all opened control structures are
  35. properly closed. See !CSP and ?PAIRS.
  36.  
  37.  
  38. : ?COMP ( --- ) [FIG]
  39. when state is not compiling, then -14 THROW is executed which unless
  40. caught issues the message "interpreting a compile-only word" and
  41. aborts.
  42.  
  43.  
  44. : ?EXEC ( --- ) [FIG]
  45. when state is not interpreting, then -29 THROW is executed which
  46. unless caught issues the message "compiler nesting" and aborts.
  47.  
  48.  
  49. : ?FILE ( ior --- )
  50. takes an io-result as most words from the files word set produce.
  51. Nothing happens if the io-result is zero for "no error". If ior is
  52. non-zero ?FILE executes `-256 SWAP - THROW' which unless caught issues
  53. an appropriate error message and aborts. The error message wording
  54. stems from a call to strerror().
  55.  
  56.  
  57. : ?LOADING ( --- ) [FIG]
  58. nothing happens when executed while a block is loaded. Otherwise
  59. executes -35 THROW which unless caught issues the message "invalid
  60. block number" and aborts. Typical use in words that do relative
  61. loading like --> or +THRU.
  62.  
  63.  
  64. : ?PAIRS ( n1 n2 --- ) [FIG]
  65. usage only when compiling.
  66. If n1 and n2 are equal nothing happens. Otherwise executes -22 THROW
  67. which unless caught issues the message "control structure mismatch"
  68. and aborts. See ?CSP.
  69.  
  70.  
  71. : ?STACK ( --- ) [FIG]
  72. if one of the three stacks (data-, return- and floating point-stack)
  73. over- oder underflows then ?STACK executes the appropriate THROW:
  74.     -3    data stack overflow
  75.     -4    data stack underflow
  76.     -5    return stack overflow
  77.     -6    return stack underflow
  78.     -44    floating point stack overflow
  79.     -45    floating point stack underflow
  80. which unless caught issues the above message and aborts.
  81.  
  82.  
  83. : TOGGLE ( c-addr char --- ) [FIG]
  84. stores at c-addr: the result of an exclusive or between the character
  85. at c-addr and char. Thus toggles all bits at c-addr that are set in
  86. char.
  87.  
  88.  
  89. : LATEST ( --- c-addr ) [FIG]
  90. returns the address of the count byte of the name of the topmost word
  91. in the compilation word-list. If the compilation word list hasn't
  92. changed since the last defintion and if no words have been deleted
  93. from the dictionary since the last definition then this is the most
  94. recently defined word. In traditional singly linked dictionaries,
  95. LATEST can be defined as `CURRENT @ @', in pfe it's `CURRENT @ TOPMOST
  96. @'.  See: LAST, CURRENT, TOPMOST, WL-HASH.
  97.  
  98.  
  99. : SMUDGE ( --- )
  100. Sets bit 5 in the count byte of the most recent definition's
  101. name. This prevents the definition from being found in dictionary
  102. searches before it is properly finished, e.g. after CREATE in `:'.
  103. See UNSMUDGE, LAST.
  104.  
  105.  
  106. : UNSMUDGE ( --- )
  107. Clears bit 5 in the count byte of the most recent definition's name.
  108. This allows the definition to be found in dictionary searches. Use
  109. when a defintion is finished, e.g. in `;'. See SMUDGE, LAST.
  110.  
  111.  
  112. : UD.R ( ud n --- )
  113.  
  114. displays the unsigned double number ud right-adjusted in a field of
  115. width of at least n. No trailing space is displayed.
  116.  
  117.  
  118. : UD. ( ud --- )
  119. displays the unsigned double number ud with a trailing space.
  120.  
  121.  
  122. : .NAME ( c-addr --- )
  123. c-addr is the address of the count byte of a defintion's name. Prints
  124. the name of the definition with a trailing space.
  125.  
  126.  
  127. : -ROLL ( x(n) x(n-1) ... x1 x0 n --- x0 x(n) x(n-1) ... x1 )
  128. after removing n from the stack, rotates n+1 items on the top of the
  129. stack such that the topmost element becomes the (n+1)st element.
  130.  
  131.  
  132. : R>DROP ( R: x --- )
  133. removes the topmost element from the return stack.
  134.  
  135.  
  136. : DUP>R ( x --- x ) ( R: --- x )
  137. places a copy of the top element of the data stack on the return
  138. stack.
  139.  
  140.  
  141. : RANDOM ( n1 --- n2 )
  142. returns a random number in the range [0, n1-1].
  143.  
  144.  
  145. : SRAND ( n --- )
  146. initializes the random number generator with a seed n.
  147.  
  148.  
  149. : UNDER+ ( n1 n2 --- n1+n2 n2 )
  150. adds the top element to the second without removing the top element.
  151. Same as `SWAP OVER + SWAP'.
  152.  
  153.  
  154. : +TO ( x "<spaces>name" --- )
  155. adds x to the contents of the VALUE or local variable "name".
  156. See TO, VALUE, LOCALS|.
  157.  
  158.  
  159. : BUILD-ARRAY ( n1 n2 ... nX X --- n )
  160. stores n1 through nX into the dictionary and returns the product
  161. n = n1*n2*...*nX.
  162. n1...nX are upper bounds for indices of a multi-dimensional array.
  163. n is the resulting total number of elements. See ACCESS-ARRAY.
  164.  
  165.  
  166. : ACCESS-ARRAY ( i1 i2 ... iX a-addr1 --- a-addr2 n )
  167. at a-addr1 a list of numbers as stored by BUILD-ARRAY is expected.
  168. Multiplies and adds actual indices i1...iX with stored upper bounds
  169. n1...nX giving n, the linear offset of the element specified by
  170. i1...iX.
  171. a-addr2 is `a-addr1 X CELLS +', i.e. points just after the stored list
  172. of upper bounds.
  173.  
  174.  
  175. : 0<= ( n --- flag )
  176. flag is true (-1) if n is less than or equal to 0, false (0) otherwise.
  177.  
  178.  
  179. : 0>= ( n --- flag )
  180. flag is true (-1) if n is greater than or equal to 0, false (0) otherwise.
  181.  
  182.  
  183. : <= ( n1 n2 --- flag )
  184. flag is true (-1) if n1 is less than or equal to n2, false (0) otherwise.
  185.  
  186.  
  187. : >= ( n1 n2 --- flag )
  188. flag is true (-1) if n1 is greater than or equal to n2, false (0) otherwise.
  189.  
  190.  
  191. : U<= ( u1 u2 --- flag )
  192. flag is true (-1) if u1 is less than or equal to u2, false (0) otherwise.
  193.  
  194.  
  195. : U>= ( u1 u2 --- flag )
  196. flag is true (-1) if u1 is greater than or equal to u2, false (0) otherwise.
  197.  
  198.  
  199. : UMAX ( u1 u2 --- u3 )
  200. u3 is the greater of u1 and u2.
  201.  
  202.  
  203. : UMIN ( u1 u2 --- u3 )
  204. u3 is the lesser of u1 and u2.
  205.  
  206.  
  207. : SOURCE-LINE ( --- n )
  208. n is the line of source currently interpreted when loading a text file
  209. with INCLUDED or when loading a block it's the current input position
  210. divided by 64. If not loading from a block or a file, n is 0.
  211.  
  212.  
  213. : POCKET ( n --- addr u )
  214. returns the string stored in the n-th buffer used by S" or C". S" and
  215. C" use a set of buffers in cyclical manner.
  216.  
  217.  
  218. : LAST ( --- c-addr )
  219. returns the address of the count byte of the name of the most recently
  220. defined word. If the compilation word list has changed since the most
  221. recent definition this doesn't affect LAST. If the most recent
  222. definition has been deleted meanwhile, then the address returned by
  223. LAST is invalid. See CREATE, LATEST.
  224.  
  225.  
  226. : TOPMOST ( wid --- a-addr )
  227. in a-addr points to: a pointer to the count byte of the topmost
  228. definition in the given wordlist. See LATEST, WL-HASH.
  229.  
  230.  
  231. : WL-HASH ( c-addr n1 --- n2 )
  232. n2 is a hash code formed from the string at c-addr with length n1.
  233. This is the hash function used to select one of multiple threads
  234. (linked lists of definitions) in the dictionary. Words are stored in
  235. and must be searched in the thread computed by this function. Of
  236. course FIND hides these details. WL-HASH is provided in case you want
  237. to define your own kind of FIND.
  238.  
  239.  
  240. : WWORDS ( "<spaces>pattern" --- )
  241. Parses the input for a space-delimited search pattern. Displays all
  242. words from the first word list in the search order that match this
  243. pattern. Form patterns with wildcards '?' and '*' like this:
  244.     * matches any sequence of characters
  245.     ? matches any single character
  246.     \ quotes * and ?
  247.     any other character matches this character
  248. Examples:
  249.     WWORDS ??    displays all words with two letters
  250.     WWORDS E*    displays all words beginning with E
  251.     WWORDS F*A*    displays all words beginning with F having
  252.             an A in the name.
  253.     WWORDS *\?    displays all words ending with '?'.
  254.  
  255.  
  256. : W@ ( a-addr --- n )
  257. n is the 16 bit integer stored at a-addr.
  258.  
  259.  
  260. : W! ( x a-addr --- )
  261. stores the least significant 16 bit of x at a-addr.
  262.  
  263.  
  264. : W+! ( x a-addr --- )
  265. adds the least significant 16 bit of x to the 16 bit integer stored at
  266. a-addr.
  267.  
  268.  
  269. : (FORGET) ( addr --- )
  270. deletes all words stored above addr from the dictionary.
  271.  
  272.  
  273. : TAB ( n --- )
  274. displays at least one and as many spaces as neccessary to make the
  275. column number -- stored in the variable OUT -- divisible by n.
  276.  
  277.  
  278. : BACKSPACE ( --- )
  279.